Project Structure

BindAI projects provide a consistent way to organize agents, tools, workflows, knowledge, memory, templates, configuration, and tests. You can use BindAI components without creating a project, but a project provides a convenient structure for keeping an AI application organized as it grows.

Creating a Project

Create a new project with the BindAI CLI:

bindai new my-ai-app

Move into the project:

cd my-ai-app

The generated project provides a starting point for building a BindAI application. The project scaffold can evolve as BindAI’s CLI and templates develop, so the exact generated files may vary between versions.

Default Project Layout

A BindAI application can be organized around the following structure:

my-ai-app/
├── agents/
├── tools/
├── workflows/
├── knowledge/
├── memory/
├── templates/
├── tests/
├── .env
├── bindai.toml
└── main.py

Not every application needs every directory. Each component should be introduced when the application requires it.

Project Files

`main.py`

main.py can serve as the application’s entry point. A simple application can create an agent and execute it:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

result = agent.run("Hello!")

print(result.output)

The entry point can also start a larger application containing workflows, multiple agents, tools, or other BindAI components.

`bindai.toml`

bindai.toml is the project-level BindAI configuration file. It can be used to keep application configuration separate from Python source code. The exact configuration supported by a project depends on the BindAI version and the components being used. Keep secrets such as API keys out of bindai.toml. Use environment variables or another secure secret-management mechanism for credentials.

`.env`

The local .env file can contain environment variables required by the application. For example:

OPENAI_API_KEY=your_api_key_here

Other supported providers can use their corresponding environment variables:

ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Ollama generally uses a local model service rather than a hosted API key. Never commit API keys or other secrets to source control.

Agents

The agents/ directory can contain application-specific agent definitions. For example:

agents/
├── assistant.py
├── researcher.py
├── planner.py
└── reviewer.py

A simple agent can be defined with Agent.builder():

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

Larger applications can use multiple specialized agents. For example:

agents/
├── assistant.py
├── researcher.py
├── writer.py
└── reviewer.py

Each agent can have its own instructions, tools, memory, knowledge, retrieval configuration, and execution behavior.

Tools

The tools/ directory can contain reusable tools used by agents. For example:

tools/
├── calculator.py
├── search.py
├── weather.py
└── database.py

A tool can be defined with the BindAI tool decorator:

from bindai import tool


@tool
def echo(text: str) -> str:
    return text

The tool can then be supplied to an agent:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(echo)
    .instructions("You are a helpful assistant.")
    .build()
)

Tools can represent Python functions, APIs, application services, database operations, search functionality, external connections, or MCP-backed capabilities.

Workflows

The workflows/ directory can contain workflow-related application code. For example:

workflows/
├── support.py
├── onboarding.py
└── reports.py

Workflows can coordinate:

Agents
Tools
Conditional execution
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human tasks

Separating workflows from agents and tools makes larger applications easier to maintain. A workflow can also combine multiple specialized agents:

Workflow
   │
   ├── Research Agent
   │
   ├── Writing Agent
   │
   └── Review Agent

Knowledge

The knowledge/ directory can contain application resources used by knowledge and retrieval systems. For example:

knowledge/
├── docs/
├── manuals/
└── policies/

Knowledge resources can be processed through BindAI’s knowledge and retrieval pipeline. The knowledge system supports capabilities including:

Document ingestion
Parsing
Chunking
Embeddings
Metadata
Semantic retrieval
BM25 retrieval
Hybrid retrieval
Filtering
Reranking
Conversational retrieval
Knowledge pipelines

Knowledge can then be connected to an agent:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .knowledge(knowledge)
    .instructions("Answer questions using the available knowledge.")
    .build()
)

Memory

The memory/ directory can be used to organize application-specific memory resources or implementations. BindAI provides several memory implementations, including:

In-memory memory
SQLite
PostgreSQL
Vector memory
Pinecone
Chroma
Conversation memory
Custom memory implementations

Memory can be configured for an agent:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .memory(memory)
    .instructions("You are a helpful assistant.")
    .build()
)

The actual storage mechanism depends on the selected memory implementation.

Templates

The templates/ directory can contain reusable application or workflow templates. For example:

templates/
├── workflow-basic.md
├── workflow-condition.md
└── workflow-review.md

Templates can help teams standardize common application patterns. BindAI also provides workflow templates covering patterns such as:

Basic workflows
Conditions
Loops
Parallel execution
Human tasks
Retries
Timeouts
Scheduling

Tests

Store project tests inside the tests/ directory. For example:

tests/
├── test_agents.py
├── test_tools.py
└── test_workflows.py

Run the project’s tests with:

pytest

Tests should cover important application behavior, including agent execution, tool behavior, workflows, integrations, and other components used by the application.

Connections

Applications that communicate with external services can organize connection-related code separately from agents and workflows. BindAI’s Connections package currently provides integrations for:

Webhooks
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

For example:

connections/
├── github.py
├── slack.py
└── notifications.py

The exact organization is application-specific. Keeping external-service communication separate from agent logic makes integrations easier to test and replace.

MCP

Applications using Model Context Protocol can keep MCP-related configuration and integration code separate from core agent logic. BindAI’s current MCP support includes:

MCP client connections
Tool discovery
Tool calling
MCP tools exposed through the BindAI tool system

For example:

mcp/
├── servers.py
└── tools.py

MCP resources and advanced protocol capabilities can be added as the MCP implementation expands.

Organizing Larger Projects

As an application grows, organize components by responsibility. For example:

my-ai-app/
│
├── agents/
│   ├── assistant.py
│   ├── planner.py
│   └── researcher.py
│
├── tools/
│   ├── search.py
│   ├── calculator.py
│   └── database.py
│
├── workflows/
│   ├── support.py
│   ├── onboarding.py
│   └── reports.py
│
├── knowledge/
│   ├── docs/
│   ├── manuals/
│   └── policies/
│
├── memory/
│
├── templates/
│
├── connections/
│
├── mcp/
│
├── tests/
│   ├── test_agents.py
│   ├── test_tools.py
│   └── test_workflows.py
│
├── bindai.toml
├── main.py
└── .env

This structure keeps responsibilities separated as the application becomes more complex.

Separating Responsibilities

A useful way to think about the project structure is:

Application
    │
    ├── Agents
    │     ├── Instructions
    │     ├── Tools
    │     ├── Memory
    │     └── Knowledge / Retrieval
    │
    ├── Workflows
    │     ├── Conditions
    │     ├── Loops
    │     ├── Parallel execution
    │     └── Human tasks
    │
    ├── Connections
    │     └── External services
    │
    ├── MCP
    │     └── External tools
    │
    └── Tests

Each layer has a focused responsibility while remaining composable with the others.

Multi-Agent Project Structure

Applications using multiple agents can organize specialists independently. For example:

agents/
├── coordinator.py
├── researcher.py
├── analyst.py
├── writer.py
└── reviewer.py

The agents can then participate in delegation or team-based execution. A larger application might follow this pattern:

Coordinator
    │
    ├── Researcher
    │
    ├── Analyst
    │
    ├── Writer
    │
    └── Reviewer

This organization works well when each agent has a clearly defined responsibility.

Environment and Source Control

Keep application secrets separate from source code. A typical project should include a .gitignore that excludes local environment files and other generated or sensitive content. For example:

.env
.venv/
__pycache__/
.pytest_cache/

Do not commit:

API keys
Access tokens
Passwords
Private credentials
Other sensitive configuration

The .env.example pattern can be used to document required environment variables without exposing their values.

Recommended Development Workflow

A typical BindAI project workflow is:

Create a project with bindai new.
Configure the project’s environment.
Configure the required provider.
Build agents inside agents/.
Add reusable tools inside tools/.
Add memory when persistent or conversational state is required.
Add knowledge and retrieval when application-specific information is required.
Add workflows when execution requires multiple coordinated steps.
Add Connections when external services are required.
Add MCP integrations when external MCP tools are required.
Add templates for reusable application patterns.
Write tests inside tests/.
Run the application with the BindAI CLI.

The project structure is intentionally modular so an application can grow from a simple assistant into a larger AI system without placing all of its logic in a single module.

Minimal Project

Not every project needs the complete structure. A small application can start with only:

my-ai-app/
├── main.py
├── bindai.toml
└── .env

As requirements grow, additional directories can be introduced:

my-ai-app/
├── agents/
├── tools/
├── workflows/
├── knowledge/
├── memory/
├── connections/
├── mcp/
└── tests/

This allows projects to remain simple at the beginning while still providing a path toward larger AI applications.

Next Steps

After understanding the project structure, continue with:

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

01.5 project structure

Project Structure

Creating a Project

Default Project Layout

Project Files

`main.py`

`bindai.toml`

`.env`

Agents

Tools

Workflows

Knowledge

Memory

Templates

Tests

Connections

MCP

Organizing Larger Projects

Separating Responsibilities

Multi-Agent Project Structure

Environment and Source Control

Recommended Development Workflow

Minimal Project

Next Steps

​Project Structure

​Creating a Project

​Default Project Layout

​Project Files

​main.py

​bindai.toml

​.env

​Agents

​Tools

​Workflows

​Knowledge

​Memory

​Templates

​Tests

​Connections

​MCP

​Organizing Larger Projects

​Separating Responsibilities

​Multi-Agent Project Structure

​Environment and Source Control

​Recommended Development Workflow

​Minimal Project

​Next Steps

Project Structure

Creating a Project

Default Project Layout

Project Files

`main.py`

`bindai.toml`

`.env`

Agents

Tools

Workflows

Knowledge

Memory

Templates

Tests

Connections

MCP

Organizing Larger Projects

Separating Responsibilities

Multi-Agent Project Structure

Environment and Source Control

Recommended Development Workflow

Minimal Project

Next Steps